home *** CD-ROM | disk | FTP | other *** search
/ PC World Komputer 2001 December / pcwk12201b.iso / Wersje pelne i specjalne / Winamp 2.77 i 3.0beta / wasabi-sdk_beta1.exe / docs / codingstyle.txt next >
Text File  |  2001-10-08  |  6KB  |  211 lines
  1. Winamp 3 coding style sheet
  2. ver 2 -- 23-Sep-2000 brennan
  3. ver 3 -- 04-jan-2000 brennan    more C++ coding tips added
  4. ver 4 -- 21-may-2001 brennan    Dispatchable example
  5.  
  6. // *********** defining a class in general **********
  7.  
  8. #define CLASSNAME_PARENT ParentClass        // #defines all CAPS
  9. const int MAGICNUM=47;    // use const int instead of #define when possible
  10. class ClassName : public CLASSNAME_PARENT {    // front and bi capitalized
  11. public:    // section names fully to the left
  12.   ClassName();
  13.   ~ClassName();
  14.  
  15.   void doSomething();    // bicapitalized
  16.  
  17. protected:
  18.   void andSomethingElse();
  19.  
  20. private:
  21.   int privdata;    // all lowercased
  22.   // don't use 1- or 2- character member names so as to avoid conflict
  23.   // with common method parameters (such as i, w, h, etc.)
  24. };
  25.  
  26. ClassName::ClassName() {
  27.   // init data here
  28. }
  29.  
  30. void ClassName::doSomething() {    // brackets with the def
  31.   // note the 2-spaces used per indentation level. no tabs!
  32.  
  33.   int gaybag=7;    // define stuff as you need it, variables all lowercase
  34.   if (gaybag) {    // space after if (). same for while, for, etc.
  35.     plorf();
  36.   }
  37.  
  38.   switch (gaybag) {
  39.     case 1:
  40.     break;
  41.     case 2: {// use {} if you need stack varables, limit scope whenever possible
  42.       int flerpo;
  43.       // something
  44.     }
  45.     break;
  46.     case 3:
  47.       return;    // indent the return so it doesn't look like a break
  48.     default:
  49.       // blah
  50.     break;
  51.   }
  52. }
  53.  
  54. // ******** header file stuff **********
  55.  
  56. #ifndef _FILENAME_H
  57. #define _FILENAME_H
  58.  
  59. #include <sysfile.h>    // system files first
  60.  
  61. #include "../common/std.h" // note forward slashes
  62.  
  63. // then #defines and enums
  64. #define WHATEVER 7    // avoid macros, but make em uppercase if you use em
  65. namespace Blonk {    // put enums in namespaces when appropriate
  66.   enum { BLAH, PLOO };
  67.   const int flork = 89;
  68. };
  69.  
  70. // classes and function prototypes here
  71.  
  72. // externs last
  73. extern GUID component_guid;
  74.  
  75. #endif
  76.  
  77. // ******** naming a component class **********
  78.  
  79. class WACname : public WAComponentClient {
  80. };
  81.  
  82. // ******** for fully abstract base classes, name them like this ********
  83.  
  84. // this is only an interface
  85. class AbstractClass {
  86. public:
  87.   virtual int whatever()=0;
  88. };
  89.  
  90. // this is the implementation of the interface
  91. class AbstractClassI {
  92. public:
  93.   virtual int whatever();
  94. };
  95.  
  96. // ******** Dispatchable classes **********
  97.  
  98. Here is an example of a safe interface to an object. The interface is Thing
  99. and the instance of it is ThingI.
  100.  
  101. class Thing : public Dispatchable {
  102. public:
  103.   int method1(int a, int b) { return _call(METHOD1, 0, a, b); }
  104.   void method2(float z) { _voidcall(METHOD2, z); }
  105.  
  106.   enum {
  107.     METHOD1,
  108.     METHOD2,
  109.   };
  110. };
  111.  
  112. class ThingI : public Thing {
  113. public:
  114.   ThingI();
  115.  
  116.   // Dispatchable handles both regular and virtual methods
  117.   int method1(int a, int b);
  118.   virtual void method2(float z);
  119.  
  120.   RECVS_DISPATCH;
  121. };
  122.  
  123. // in .cpp file
  124. #define CBCLASS ThingI
  125. START_DISPATCH;
  126.   CB(METHOD1, method1);
  127.   VCB(METHOD2, method2);
  128. END_DISPATCH;
  129.  
  130. // ******** Code markers **********
  131.  
  132. - Use //CUT for something that is commented out because it needs to go away
  133. once you're sure it won't need to come back.
  134.  
  135. - Use //TODO for something that you intend to come back and improve
  136.  
  137. - Use //FUCKO for something you need to fix because it's just broken or
  138.   wrong. Stuff that someone really must look at before a release.
  139.  
  140. --------------------------------------------------------
  141. C++ coding notes
  142. --------------------------------------------------------
  143.  
  144. *** 21-may-2001
  145.  
  146. Seriously. If you use char* when you could use const char*, I might have to kill
  147. you.
  148.  
  149.  
  150. *** 04-Jan-2001
  151.  
  152. - Do NOT use char *, STRDUP and FREE any more for strings. Always use String
  153. if at all possible. It's clean and fast and all inline and basically free.
  154. It auto-deletes in the destructor and handles assignment properly.
  155.  
  156. - You don't usually need to use a PtrList<>*. Just put the PtrList<> in your
  157. object. It will free its memory in its destructor when your object is destroyed,
  158. and it only takes up 12 bytes of memory when empty so you're not saving much
  159. by allocating it with new.
  160.  
  161. - Any time you find yourself coding the same basic thing twice, try to invent
  162. a useful object that can do the job in a general fashion. i.e. PathParser.
  163. Remember, there are two basic kinds of classes: abstract (fat) & concrete (basic
  164. types). We have plenty of the former and don't use enough of the latter.
  165.  
  166.  
  167. *** 11-Dec-2000
  168.  
  169. - Use const for pointers whenever possible:
  170.     - To guarantee a function will not modified the pointed-to object
  171.     - return const * to guarantee no one can modify what you're returning
  172.     - This is especially important for char *'s
  173.  
  174. - Use const ints instead of #define for magic numbers. Use enums when you
  175. just need a range of magic numbers. Anonymous enums are ok for flags.
  176.  
  177. *** 18-Nov-2000
  178.  
  179. - let's stop using C-style casts. All code should start using
  180.   static_cast : for casting from/to void *
  181.   reinterpret_cast : for casting from/to ints, LPARAMs, etc.
  182.   By switching some code to use these I've already found some possibly weird
  183.   behavior that could have come up in the API system.
  184.  
  185. - use the const operator on all methods where it works, i.e. simple get fns
  186.     int getNumItems() const { return nitems; }
  187.  
  188. ***
  189.  
  190. - Remember, it is safe to call 'delete' with a NULL pointer.
  191.     "if (ptr != NULL) delete ptr;" is redundant.
  192.  
  193. - If a function does not have to be virtual, don't make it virtual
  194.  
  195. - Always make destructors virtual (*if* another module could delete them)
  196.  
  197. - Make constructors protected if they should never be instantiated.
  198.   This is almost always true for classes that are meant to be inherited
  199.   from.
  200.  
  201. - Never call any virtual functions from within a constructor or destructor
  202.   unless you are trying to create insane bugs
  203.  
  204. - PLEASE try to keep the same order for functions in the .CPP as in the .H
  205.  
  206. - Never ever check in code with known bugs
  207.  
  208. - Code as if the next person who might have to work on your code is a 6'+
  209.   210 lb. irritable heavy-drinking sumo champ who knows where you live. Because
  210.   I do.
  211.